Skip to main content

Verification Sessions Endpoint

To start a verification process, use the following endpoint:

POST https://app.trustchex.com/api/v1/verification-sessions

Add the API key as x-api-key in the header.

Request Body​

Include the following properties in the body:

{
    "workflowId": "<workflowId>",
    "email": "<user email>",
    "phoneNumber": "<user phone>",
    "sendOTP": true,
    "locale": "<en|tr>",
    "duration": 30
}

JSON Properties​

  • workflowId (string, required): The ID of the workflow to be used for verification. You can create a workflow at the workflows section.
  • email (string, optional): The email address of the user to be verified. Either email or phoneNumber must be provided, but not both.
  • phoneNumber (string, optional): The phone number of the user to be verified. Either phoneNumber or email must be provided, but not both.
  • sendOTP (boolean, optional, default: true): If set true, user's email or phone number will be validated with One Time Password. If you already confirmed the user has the real ownership, you can set it to false to make the process simpler.
  • locale (string, required): The language preference for the verification process. Acceptable values are en for English and tr for Turkish.
  • duration (integer, optional): The duration of the verification session in minutes. The default value is 30 minutes.

JavaScript Fetch Example​

Here is an example of how to make the API request using JavaScript's fetch:

const url = 'https://app.trustchex.com/api/v1/verification-sessions';
const apiKey = 'YOUR_API_KEY';
const requestBody = {
    email: '[email protected]',
    workflowId: 'workflow123',
    sendOTP: true,
    locale: 'en',
    duration: 30
};

fetch(url, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
    },
    body: JSON.stringify(requestBody)
})
.then(response => response.json())
.then(data => {
    console.log('Success:', data);
})
.catch((error) => {
    console.error('Error:', error);
});

Successful Response​

A successful response will return a JSON object with the following structure:

{
    "id": "<verificationSessionId>",
    "identificationId": "<identificationId>",
    "deepLink": "trustchex://app-url/https://app.trustchex.com/verification-session/<verificationSessionId>",
    "qrCodeLink": "https://app.trustchex.com/api/v1/verification-sessions/<verificationSessionId>/qr-code",
    "sessionPageLink": "https://app.trustchex.com/public/verification-sessions/<verificationSessionId>"
}

Response Properties​

  • id (UUID): The unique identifier for the verification session.
  • identificationId (UUID): The unique identifier for the identification process.
  • deepLink (string): A deep link URL for the verification session.
  • qrCodeLink (string): A URL to the QR code for the verification session.
  • sessionPageLink (string): A URL to the verification session page which helps the user to find the mobile app links together with a QR code or deep link.

The deepLink and qrCodeLink should be used in the application that integrates the KYC solution to direct the user to the mobile app.

  • Deep Link: The deepLink can be used to send the user directly to the mobile app by clicking on the link.
  • QR Code Link: The qrCodeLink can be used to generate a QR code that the user can scan to be directed to the mobile app.

Error Handling​

If there is an error with the request, the API will return an appropriate HTTP status code and a JSON object with error details.

  • 400 Bad Request: The request body is invalid or missing required fields.
  • 401 Unauthorized: The API key is missing or invalid.
  • 500 Internal Server Error: An error occurred on the server.

Make sure to handle these errors appropriately in your application.